docs: add performance benchmarks, pprof analysis, and tuning trade-offs by ankurs · Pull Request #54 · go-coldbrew/docs.coldbrew.cloud

ankurs · 2026-04-04T13:39:48Z

Summary

Add end-to-end throughput numbers from ghz load testing across 3 configs (default, tuned, bare gRPC) to architecture.md
Add pprof-under-load workflow with CPU/heap breakdown and the "cumulative CPU != throughput impact" nuance to Debugging.md
Add RESPONSE_TIME_LOG_ERROR_ONLY and DISABLE_UNIX_GATEWAY to high-throughput example, measured tuning impact table, and histogram trade-off warning to config-reference.md
Add histogram disappearance warning on latency alerts and RESPONSE_TIME_LOG_ERROR_ONLY to production checklist in production.md
Add ~10-12% overhead claim to hero text in Index.md

Test plan

All 56 Playwright tests pass
Verify rendered pages on GitHub Pages preview
Confirm internal links resolve (/architecture#interceptor-chain-overhead, /config-reference#measured-tuning-impact)

Summary by CodeRabbit

Documentation

Added performance metrics – Documented interceptor chain overhead estimates and benchmark results for default vs. tuned configurations.
Updated production guidance – Enhanced configuration recommendations for high-throughput scenarios with new tuning examples and performance impact notes.
Expanded debugging resources – Added CPU and memory profiling workflows under realistic load conditions with analysis examples.
Clarified feature dependencies – Updated documentation to explicitly state which features depend on specific settings.

Add end-to-end throughput numbers from ghz load testing (50k default, 53k tuned, 56k bare gRPC at c=200 on M1 Pro) and pprof CPU/heap breakdown under load. Key additions: - architecture.md: new "Interceptor Chain Overhead" section with RPS comparison table and the ~10-12% overhead framing - Debugging.md: pprof-under-load workflow with CPU breakdown table and the critical "cumulative CPU != throughput impact" nuance - config-reference.md: RESPONSE_TIME_LOG_ERROR_ONLY and DISABLE_UNIX_GATEWAY added to high-throughput example, measured tuning impact table, histogram trade-off warning - production.md: histogram disappearance warning on latency alerts, RESPONSE_TIME_LOG_ERROR_ONLY in production checklist - Index.md: overhead claim in hero text

coderabbitai · 2026-04-04T13:40:01Z

Warning

Rate limit exceeded

@ankurs has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 13 minutes and 59 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 13 minutes and 59 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b111bc59-1604-4155-a366-094fce5cbc07

📥 Commits

Reviewing files that changed from the base of the PR and between fb37e12 and f6672ef.

📒 Files selected for processing (2)

architecture.md
config-reference.md

📝 Walkthrough

Walkthrough

This pull request updates documentation across five files to quantify gRPC interceptor chain performance impact (~10–12% overhead), add benchmark results, introduce configuration tuning environment variables, clarify Prometheus histogram behavior when disabled, and document profiling workflows under gRPC load.

Changes

Cohort / File(s)	Summary
Homepage & Marketing `Index.md`	Updated "Production-proven" statement to include quantified interceptor overhead percentage (~10–12%).
Architecture & Performance Benchmarks `architecture.md`, `config-reference.md`	Added new sections documenting interceptor chain overhead with benchmark results (throughput/RPS, latency), per-interceptor micro-benchmarks, and measured tuning impact across default vs. tuned vs. no-interceptor configurations.
Configuration Reference `config-reference.md`	Clarified `ENABLE_PROMETHEUS_GRPC_HISTOGRAM` behavior (disabling removes percentile queries), added `RESPONSE_TIME_LOG_ERROR_ONLY=true` to high-throughput example, enabled Unix socket gateway (`DISABLE_UNIX_GATEWAY=false`), and added warning block regarding histogram removal impact.
Operational Guides `howto/Debugging.md`, `howto/production.md`	Added profiling-under-load workflow (CPU and allocation profiling with `ghz` and pprof); updated histogram documentation to note availability only when enabled; added production checklist recommendation for error-only response logging and warning about silent alert failures when histograms disabled.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

docs: update for OTEL migration — remove OpenTracing references #44: Modifies architecture.md interceptor-chain documentation section; directly overlaps with this PR's performance overhead additions.
Docs: improve approachability, discoverability, and content depth #39: Changes config-reference.md, howto/Debugging.md, and howto/production.md around gRPC interceptors, Prometheus histogram flags, and profiling; significant overlap in scope and modified sections.
docs: add throughput config options, NR auto-disable note, high-throughput example #48: Updates config-reference.md high-throughput example and RESPONSE_TIME_LOG_ERROR_ONLY configuration; directly related to the high-throughput tuning example changes in this PR.

Poem

🐰 Benchmarks now clear, overhead shown,
Ten percent the cost of features honed,
Profiling paths and configs laid bare,
Performance truth, documented with care!
Whiskers twitch with metrics delight—
Data shines, production-bright! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main changes: adding performance benchmarks, pprof analysis documentation, and tuning trade-offs across multiple documentation files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/performance-benchmarks-and-tuning-guide

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

🧹 Nitpick comments (1)

howto/Debugging.md (1)
50-51: Clarify ghz prerequisites to avoid copy-paste failures.

Consider adding a short note that this command assumes server reflection is enabled; otherwise users should pass --proto/--import-path.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@howto/Debugging.md` around lines 50 - 51, Add a brief note in Debugging.md
near the ghz example clarifying that the ghz command shown (ghz --insecure
--call your.package.Service/Method ...) assumes server reflection is enabled on
the target gRPC server; if reflection is not enabled, instruct users to supply
the proto definition and import paths using ghz flags (e.g., --proto and
--import-path) or otherwise provide equivalent connection information so the
call succeeds.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@howto/Debugging.md`:
- Around line 50-51: Add a brief note in Debugging.md near the ghz example
clarifying that the ghz command shown (ghz --insecure --call
your.package.Service/Method ...) assumes server reflection is enabled on the
target gRPC server; if reflection is not enabled, instruct users to supply the
proto definition and import paths using ghz flags (e.g., --proto and
--import-path) or otherwise provide equivalent connection information so the
call succeeds.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5c715120-dd7e-413d-8758-0b9823641d1c

📥 Commits

Reviewing files that changed from the base of the PR and between c16a3c2 and fb37e12.

📒 Files selected for processing (5)

Index.md
architecture.md
config-reference.md
howto/Debugging.md
howto/production.md

Copilot

Pull request overview

Adds performance-focused documentation across the docs site, tying together ghz throughput benchmarks, pprof-under-load guidance, and configuration trade-offs for high-QPS services.

Changes:

Document interceptor-chain throughput overhead (default vs tuned vs bare gRPC) and link it from the home page hero text.
Add a “profiling under gRPC load” workflow (ghz + pprof CPU/heap) and clarify how to interpret cumulative CPU vs throughput.
Expand high-throughput configuration guidance with measured tuning impact and explicit warnings about disabling Prometheus histograms.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
Index.md	Updates hero text with a linked claim about interceptor-chain overhead.
howto/production.md	Adds histogram/latency-alert caveat and includes `RESPONSE_TIME_LOG_ERROR_ONLY` in the production checklist.
howto/Debugging.md	Adds a step-by-step pprof-under-load workflow using ghz plus interpretation guidance.
config-reference.md	Updates histogram config description; expands high-throughput example; adds measured tuning impact + warnings.
architecture.md	Adds a new section quantifying interceptor-chain overhead and pointing to relevant tuning knobs.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…l interaction - Rename table columns from 'c=N RPS' to 'RPS @ c=N' to disambiguate concurrency from throughput - Add RESPONSE_TIME_LOG_LEVEL=warn to high-throughput example to clarify interaction with LOG_LEVEL

Copilot AI review requested due to automatic review settings April 4, 2026 13:39

Copilot started reviewing on behalf of ankurs April 4, 2026 13:40 View session

coderabbitai Bot reviewed Apr 4, 2026

View reviewed changes

Copilot AI reviewed Apr 4, 2026

View reviewed changes

Comment thread config-reference.md Outdated

Comment thread architecture.md Outdated

Comment thread config-reference.md Outdated

ankurs merged commit 6362d5c into main Apr 4, 2026
7 checks passed

ankurs deleted the docs/performance-benchmarks-and-tuning-guide branch April 4, 2026 13:49

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add performance benchmarks, pprof analysis, and tuning trade-offs#54

docs: add performance benchmarks, pprof analysis, and tuning trade-offs#54
ankurs merged 2 commits intomainfrom
docs/performance-benchmarks-and-tuning-guide

ankurs commented Apr 4, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Apr 4, 2026 •

edited

Loading

Rate limit exceeded

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

ankurs commented Apr 4, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Summary by CodeRabbit

Documentation

Uh oh!

coderabbitai Bot commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rate limit exceeded

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ankurs commented Apr 4, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Apr 4, 2026 •

edited

Loading